home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / Extras / opussdk / docs / ipc.doc < prev    next >
Text File  |  1996-09-05  |  12KB  |  337 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/IPC_Command
  4. dopus5.library/IPC_FindProc
  5. dopus5.library/IPC_Flush
  6. dopus5.library/IPC_Free
  7. dopus5.library/IPC_Launch
  8. dopus5.library/IPC_ListCommand
  9. dopus5.library/IPC_ProcStartup
  10. dopus5.library/IPC_Reply
  11. dopus5.library/IPC_Command                         dopus5.library/IPC_Command
  12.  
  13.     NAME
  14.         IPC_Command - send a command to an IPC process
  15.  
  16.     SYNOPSIS
  17.         IPC_Command(ipc, command, flags, data, data_free, reply)
  18.                      A0    D0      D1     A1      A2       A3
  19.  
  20.         ULONG IPC_Command(IPCData *, ULONG, ULONG, APTR, APTR,
  21.                           struct MsgPort *);
  22.  
  23.     FUNCTION
  24.         Sends a command to an IPC process. Can be used from a non-IPC
  25.         process but this is not recommended.
  26.  
  27.     INPUTS
  28.         ipc - IPC process to send command to
  29.  
  30.         command - command code (application-specific)
  31.  
  32.         flags - command flags (application-specific)
  33.  
  34.         data - command data (application-specific)
  35.  
  36.         data_free - additional data. The data specified here will be
  37.                     automatically freed with FreeVec() when the message
  38.                     is replied to, so you MUST allocate it with
  39.                     AllocVec().
  40.  
  41.         reply - reply port. You can either specify a message port for
  42.                 the reply, or use one of these special values :
  43.  
  44.                     REPLY_NO_PORT     - use default port for reply
  45.                     REPLY_NO_PORT_IPC - specify this if the message is sent
  46.                                         from a non-IPC process
  47.  
  48.                 If you don't want a reply to this message (ie you want it
  49.                 to be sent asynchronously), specify NULL for this value.
  50.  
  51.     RESULT
  52.         The command will be sent to the specified process. If the command
  53.         was not sent asynchronously, the destination process' result code
  54.         is returned.
  55.  
  56.     NOTES
  57.         There are several reserved command codes. You are free to use these
  58.         for your own applications, or use your own codes. These are listed
  59.         in <dopus/ipc.h>.
  60.  
  61.     SEE ALSO
  62.         IPC_Launch(), IPC_Reply()
  63.  
  64. dopus5.library/IPC_FindProc                       dopus5.library/IPC_FindProc
  65.  
  66.     NAME
  67.         IPC_FindProc - find an IPC process by name
  68.  
  69.     SYNOPSIS
  70.         IPC_FindProc(list, name, activate, data)
  71.                       A0    A1      D0      D1
  72.  
  73.         IPCData *IPC_FindProc(struct ListLock *, char *, BOOL, ULONG);
  74.  
  75.     FUNCTION
  76.         This routine searches the supplied list for a named IPC process.
  77.         Optionally, it can send this process an IPC_ACTIVATE message with
  78.         user-specified data.
  79.  
  80.     INPUTS
  81.         list - ListLock to search. This routine locks this list in shared
  82.                mode, and will block until the list is available.
  83.  
  84.         name - name to search for (case sensitive)
  85.  
  86.         activate - specify TRUE if you want an IPC_ACTIVATE message to be sent
  87.                    automatically.
  88.  
  89.         data - if 'activate' is TRUE, this value will be passed in the data
  90.                field of the IPC_ACTIVATE command.
  91.  
  92.     RESULT
  93.         If the process is found, its IPCData pointer is returned. To ensure
  94.         that this pointer remains valid you should Forbid(), or lock the
  95.         list yourself (in shared mode!).
  96.  
  97.     SEE ALSO
  98.         IPC_Launch(), IPC_Command()
  99.  
  100. dopus5.library/IPC_Flush                             dopus5.library/IPC_Flush
  101.  
  102.     NAME
  103.         IPC_Flush - flush an IPC command port
  104.  
  105.     SYNOPSIS
  106.         IPC_Flush(ipc)
  107.                    A0
  108.  
  109.         void IPC_Flush(IPCData *);
  110.  
  111.     FUNCTION
  112.         This routine searches the command port for any messages and replies
  113.         to them with an IPC_ABORT.
  114.  
  115.     INPUTS
  116.         ipc - IPCData of the process
  117.  
  118.     RESULT
  119.         The port is emptied.
  120.  
  121.     NOTES
  122.         In practice you rarely need this function.
  123.  
  124.     SEE ALSO
  125.         IPC_Free()
  126.  
  127. dopus5.library/IPC_Free                               dopus5.library/IPC_Free
  128.  
  129.     NAME
  130.         IPC_Free - free an IPC process
  131.  
  132.     SYNOPSIS
  133.         IPC_Free(ipc)
  134.                   A0
  135.  
  136.         void IPC_Free(IPCData *);
  137.  
  138.     FUNCTION
  139.         This routine frees all the memory associated with an IPC process
  140.         entry. It does NOT remove the process itself from the system. It is
  141.         designed to be called by a process on itself, as the last step before
  142.         exiting.
  143.  
  144.     INPUTS
  145.         ipc - IPCData to free
  146.  
  147.     RESULT
  148.         The IPCData handle is freed. If the process was a member of a list,
  149.         it is removed from that list. Any commands still in its message port
  150.         are replied to with IPC_ABORT.
  151.  
  152.     SEE ALSO
  153.         IPC_Launch()
  154.  
  155. dopus5.library/IPC_Launch                           dopus5.library/IPC_Launch
  156.  
  157.     NAME
  158.         IPC_Launch - launch a new process
  159.  
  160.     SYNOPSIS
  161.         IPC_Launch(list, ipcptr, name, entry, stack, data, doslib)
  162.                     A0     A1     A2     D0    D1     D2     A3
  163.  
  164.         long IPC_Launch(struct ListLock *, IPCData **, char *,
  165.                         ULONG, ULONG, ULONG, struct Library *);
  166.  
  167.     FUNCTION
  168.         The IPC routines in the dopus5.library provide an easy and efficient
  169.         way to implement multi-threading in your application. Using the
  170.         IPC_Launch functions creates an IPCData, which is a handle to a
  171.         process. Using this handle you can easily send command between
  172.         multiple processes.
  173.  
  174.         The important fields in the IPCData structure are as follows :
  175.  
  176.             proc            - pointer to the Process structure
  177.             command_port    - port to listen to for commands
  178.             userdata        - user-specified data
  179.             memory          - a memory pool you can use
  180.  
  181.         All Opus 5 modules are launched as IPC processes, and are passed
  182.         a pointer to their IPCData structures. They are also passed the
  183.         address of the main Directory Opus IPCData structure, which allows
  184.         them to send direct commands to Opus.
  185.  
  186.         If you are writing a standalone application and wish to use the IPC
  187.         routines, your main thread will need to create an IPCData structure
  188.         manually. It must be initialised as follows :
  189.  
  190.             proc            - pointer to your main Process
  191.             command_port    - pointer to a message port
  192.             list            - NULL
  193.             reply_port      - pointer to a DIFFERENT message port
  194.  
  195.         IPC processes can automatically be added to a list. There is no
  196.         need for you to keep track of a process once it has been launched,
  197.         except that your main process can't exit while a child is still
  198.         running (as the code would be freed).
  199.  
  200.     INPUTS
  201.         list - pointer to an initialise ListLock structure if you want this
  202.                process to be automatically added to a list (can be NULL).
  203.  
  204.         ipcptr - pointer to a pointer to IPCData. If the process is launched
  205.                  successfully, the new IPCData handle will be stored in this
  206.                  address (can be NULL).
  207.  
  208.         name - name for the new process.
  209.  
  210.         entry - pointer to code for the new process.
  211.  
  212.         stack - stack size for the new process. You can also set the
  213.                 IPCF_GETPATH flag in the stack variable, to have the new
  214.                 process automatically inherit the system path list.
  215.  
  216.         data - data that is automatically passed to the new process
  217.  
  218.         doslib - you must supply a pointer to the DOS library
  219.  
  220.     RESULT
  221.         This routine returns 0 if the child process failed to launch.
  222.         However, if the child process was actually launched, but failed
  223.         to initialise because of lack of memory, or a failure in your
  224.         user-defined initialisation code (see IPC_ProcStartup), the
  225.         return value will still indicate success.
  226.  
  227.         A better way to test failure is to specify a variable for the 'ipcptr'
  228.         parameter. If this is NULL after this call, the process failed to
  229.         start.
  230.  
  231.     SEE ALSO
  232.         IPC_ProcStartup(), IPC_Command(), IPC_Free
  233.  
  234. dopus5.library/IPC_ListCommand                 dopus5.library/IPC_ListCommand
  235.  
  236.     NAME
  237.         IPC_ListCommand - send a command to a list of processes
  238.  
  239.     SYNOPSIS
  240.         IPC_ListCommand(list, command, flags, data, wait)
  241.                          A0      D0      D1    D2    D3
  242.  
  243.         void IPC_ListCommand(struct ListLock *, ULONG, ULONG, ULONG, BOOL);
  244.  
  245.     FUNCTION
  246.         Sends the same command to every process on the supplied list.
  247.         Optionally waits for a reply from every process.
  248.  
  249.     INPUTS
  250.         list - list of processes
  251.         command - command ID to send
  252.         flags - command flags
  253.         data - command data
  254.         wait - specify TRUE if you want to wait for replies
  255.  
  256.     RESULT
  257.         The command is sent to every process on the list. If 'wait' is
  258.         TRUE, does not return until every process has replied.
  259.  
  260.     SEE ALSO
  261.         IPC_Launch(), IPC_Command()
  262.  
  263. dopus5.library/IPC_ProcStartup                 dopus5.library/IPC_ProcStartup
  264.  
  265.     NAME
  266.         IPC_ProcStartup - startup code for an IPC process
  267.  
  268.     SYNOPSIS
  269.         IPC_ProcStartup(data, code)
  270.                          A0    A1
  271.  
  272.         IPCData *IPC_ProcStartup(ULONG *, ULONG *);
  273.  
  274.     FUNCTION
  275.         Your IPC process should call this routine as the very first
  276.         instruction. It receives the startup message from the parent process,
  277.         and lets you retrieve your own IPCData handle.
  278.  
  279.     INPUTS
  280.         data - pointer to a variable to receive a pointer to the data that
  281.                was passed to IPC_Launch.
  282.  
  283.         code - address of a user-supplied initialisation routine to call. If
  284.                you provide this, your routine is called from this function.
  285.                The prototype of this routine is as follows :
  286.  
  287.                     ULONG __asm code(register __a0 IPCData *ipc,
  288.                                      register __a1 APTR data)
  289.  
  290.                Your intialisation routine receives a pointer to the IPCData
  291.                handle of the new process, and a pointer to the data passed
  292.                to IPC_Launch. This routine can do pretty much anything, but
  293.                you should keep it as simple as possible (there should
  294.                certainly be no IPC functions called from within it).
  295.                Your routine should return FALSE for failure and TRUE for
  296.                success. If it returns FALSE, the IPC_ProcStartup() call will
  297.                return NULL, and the new process should then quit.
  298.  
  299.     RESULT
  300.         Returns a pointer to your new IPCData handle. The 'data' value that
  301.         was passed to IPC_Launch() is stored in the supplied variable.
  302.         If this routine returns NULL, it means an error occurred (either in
  303.         the intialisation of the new process, or in your own initialisation
  304.         code). In this case, you should exit immediately.
  305.  
  306.     SEE ALSO
  307.         IPC_Launch()
  308.  
  309. dopus5.library/IPC_Reply                             dopus5.library/IPC_Reply
  310.  
  311.     NAME
  312.         IPC_Reply - reply to an IPC message
  313.  
  314.     SYNOPSIS
  315.         IPC_Reply(msg)
  316.                    A0
  317.  
  318.         void IPC_Reply(IPCMessage *);
  319.  
  320.     FUNCTION
  321.         Call this routine to reply to IPCMessages you receive at your
  322.         command port (do not call ReplyMsg())
  323.  
  324.     INPUTS
  325.         msg - message to reply
  326.  
  327.     RESULT
  328.         The message is replied. It is possible to pass a return code back
  329.         to the sending task (providing the message was sent synchronously).
  330.         To do this, set the 'command' field of the message to the value.
  331.         This will then be the return from the IPC_Command() function for the
  332.         other process.
  333.  
  334.     SEE ALSO
  335.         IPC_Launch(), IPC_Command()
  336.  
  337.